home *** CD-ROM | disk | FTP | other *** search
/ X User Tools / X User Tools (O'Reilly and Associates)(1994).ISO / sun4c / archive / tcltk.z / tcltk / man / catn / selection.n < prev    next >
Text File  |  1994-09-20  |  7KB  |  199 lines
  1.  
  2.  
  3.  
  4. selection(n)               Tk Commands
  5.  
  6.  
  7.  
  8. _________________________________________________________________
  9.  
  10. NAME
  11.      selection - Manipulate the X selection
  12.  
  13. SYNOPSIS
  14.      selection _o_p_t_i_o_n ?_a_r_g _a_r_g ...?
  15. _________________________________________________________________
  16.  
  17.  
  18. DESCRIPTION
  19.      This command provides a Tcl interface  to  the  X  selection
  20.      mechanism  and  implements  the full selection functionality
  21.      described in the X  Inter-Client  Communication  Conventions
  22.      Manual  (ICCCM),  except  that  it supports only the primary
  23.      selection.
  24.  
  25.      The first argument to selection determines the format of the
  26.      rest  of the arguments and the behavior of the command.  The
  27.      following forms are currently supported:
  28.  
  29.      selection clear _w_i_n_d_o_w
  30.           If there is a selection anywhere on  _w_i_n_d_o_w's  display,  |
  31.           clear  it so that no window owns the selection anymore.  |
  32.           Returns an empty string.
  33.  
  34.      selection get ?_t_y_p_e?
  35.           Retrieves  the  value  of  the  primary  selection  and
  36.           returns  it  as  a  result.  Type specifies the form in
  37.           which the selection is  to  be  returned  (the  desired
  38.           ``target''  for  conversion, in ICCCM terminology), and
  39.           should be an atom name such  as  STRING  or  FILE_NAME;
  40.           see  the  Inter-Client Communication Conventions Manual
  41.           for complete details.  Type defaults  to  STRING.   The
  42.           selection  owner  may choose to return the selection in
  43.           any of several different representation  formats,  such
  44.           as  STRING,  ATOM,  INTEGER,  etc. (this format is dif-
  45.           ferent than the selection type;  see the ICCCM for  all
  46.           the  confusing  details).  If the selection is returned
  47.           in a non-string format, such as INTEGER  or  ATOM,  the
  48.           selection  command  converts  it  to string format as a
  49.           collection of fields separated by  spaces:   atoms  are
  50.           converted  to their textual names, and anything else is
  51.           converted to hexadecimal integers.
  52.  
  53.      selection handle _w_i_n_d_o_w _c_o_m_m_a_n_d ?_t_y_p_e? ?_f_o_r_m_a_t?
  54.           Creates a handler for  selection  requests,  such  that
  55.           _c_o_m_m_a_n_d will be executed whenever the primary selection
  56.           is owned by _w_i_n_d_o_w and someone attempts to retrieve  it
  57.           in  the  form  given by _t_y_p_e (e.g. _t_y_p_e is specified in
  58.           the selection get command).  _T_y_p_e defaults  to  STRING.  |
  59.           If _c_o_m_m_a_n_d is an empty string then any existing handler  |
  60.  
  61.  
  62.  
  63. Tk                                                              1
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. selection(n)               Tk Commands
  71.  
  72.  
  73.  
  74.           for _w_i_n_d_o_w and _t_y_p_e is removed.
  75.  
  76.           When the selection  is  requested  and  _w_i_n_d_o_w  is  the
  77.           selection owner and _t_y_p_e is the requested type, _c_o_m_m_a_n_d
  78.           will be executed as a Tcl command with  two  additional
  79.           numbers  appended  to  it (with space separators).  The
  80.           two additional numbers are _o_f_f_s_e_t and _m_a_x_B_y_t_e_s:  _o_f_f_s_e_t
  81.           specifies  a  starting character position in the selec-
  82.           tion and _m_a_x_B_y_t_e_s gives the maximum number of bytes  to
  83.           retrieve.  The command should return a value consisting
  84.           of at most _m_a_x_B_y_t_e_s of the selection, starting at posi-
  85.           tion  _o_f_f_s_e_t.   For  very large selections (larger than
  86.           _m_a_x_B_y_t_e_s) the selection will be retrieved using several
  87.           invocations  of  _c_o_m_m_a_n_d with increasing _o_f_f_s_e_t values.
  88.           If _c_o_m_m_a_n_d returns a string whose length is  less  than
  89.           _m_a_x_B_y_t_e_s, the return value is assumed to include all of
  90.           the remainder of  the  selection;   if  the  length  of
  91.           _c_o_m_m_a_n_d's result is equal to _m_a_x_B_y_t_e_s then _c_o_m_m_a_n_d will
  92.           be invoked again, until it eventually returns a  result
  93.           shorter  than  _m_a_x_B_y_t_e_s.   The  value  of _m_a_x_B_y_t_e_s will
  94.           always be relatively large (thousands of bytes).
  95.  
  96.           If  _c_o_m_m_a_n_d  returns  an  error  then   the   selection
  97.           retrieval  is  rejected just as if the selection didn't  |
  98.           exist at all.
  99.  
  100.           The _f_o_r_m_a_t argument specifies the  representation  that
  101.           should be used to transmit the selection to the reques-
  102.           ter (the second column of Table 2 of  the  ICCCM),  and
  103.           defaults to STRING.  If _f_o_r_m_a_t is STRING, the selection
  104.           is transmitted as 8-bit ASCII characters (i.e.  just in
  105.           the form returned by _c_o_m_m_a_n_d).  If _f_o_r_m_a_t is ATOM, then
  106.           the return value from _c_o_m_m_a_n_d is  divided  into  fields
  107.           separated  by  white space;  each field is converted to
  108.           its atom value, and the 32-bit atom value is  transmit-
  109.           ted  instead  of  the atom name.  For any other _f_o_r_m_a_t,
  110.           the return value from _c_o_m_m_a_n_d is  divided  into  fields
  111.           separated by white space and each field is converted to
  112.           a 32-bit integer;  an array of integers is  transmitted
  113.           to the selection requester.
  114.  
  115.           The _f_o_r_m_a_t argument is needed  only  for  compatibility
  116.           with selection requesters that don't use Tk.  If the Tk
  117.           toolkit is being used to retrieve  the  selection  then
  118.           the value is converted back to a string at the request-
  119.           ing end, so _f_o_r_m_a_t is irrelevant.
  120.  
  121.      selection own ?_w_i_n_d_o_w? ?_c_o_m_m_a_n_d?
  122.           If _w_i_n_d_o_w is specified, then it becomes the new  selec-  |
  123.           tion  owner  and the command returns an empty string as  |
  124.           result.  The existing owner, if any, is  notified  that  |
  125.           it has lost the selection.  If _c_o_m_m_a_n_d is specified, it  |
  126.  
  127.  
  128.  
  129. Tk                                                              2
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. selection(n)               Tk Commands
  137.  
  138.  
  139.  
  140.           is a Tcl script  to  execute  when  some  other  window  |
  141.           claims ownership of the selection away from _w_i_n_d_o_w.  If  |
  142.           neither _w_i_n_d_o_w nor _c_o_m_m_a_n_d is specified then  the  com-  |
  143.           mand returns the path name of the window in this appli-  |
  144.           cation that owns the selection, or an empty  string  if  |
  145.           no window in this application owns the selection.
  146.  
  147.  
  148. KEYWORDS
  149.      clear, format, handler, ICCCM, own, selection, target, type
  150.  
  151.  
  152.  
  153.  
  154.  
  155.  
  156.  
  157.  
  158.  
  159.  
  160.  
  161.  
  162.  
  163.  
  164.  
  165.  
  166.  
  167.  
  168.  
  169.  
  170.  
  171.  
  172.  
  173.  
  174.  
  175.  
  176.  
  177.  
  178.  
  179.  
  180.  
  181.  
  182.  
  183.  
  184.  
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195. Tk                                                              3
  196.  
  197.  
  198.  
  199.